It will be helpful to read this file before compiling any samples. Some of them are intended to illustrate quite specific ideas and you may be confused by their purpose or errors issued.
This directory contains several sample scripts (ASP and WSH) intended to illustrate the ASPC features. Some of the samples contain code which will cause warnings or errors. These errors and warnings are intended to show you how to avoid them in your applications. You should read the sample description (below) and understand how to correct the corresponding error/warning or how to use the example.
Some of the examples will illustrate just how to convert your scripts to COM DLLs, but others are more complex and show how to use that code in another applications. Thus please use this document as a tutorial and read about the purpose of the corresponding example before compiling and testing it.
All the samples are structured as follows:
They are in separate directories. The project file is the only file in their
directory, source files are in a subdirectory of the sample's folder - named src.
All the projects are configured to output the loader files in "compiled"
subdirectory. The VB project is generated in VBProject subdirectory. Some
examples may contain additional directories and files see the corresponding
sample description below for more info about their purpose. It is not important
where the DLL will be created - we recommend to create it in the same directory
as VB project in order to keep the samples structure clear but it is your
choice.
And before starting: It will be very helpful to download and use ALP to test the ASP examples. It allows you to start them as desktop applications (from the windows shell's right menu for ASP files). You do not need registered version for such usage.
Go to Basic examples, Additional examples
Directory: wsh\simple
This is a "Hello world" example written for Windows Scripting Host. It is intended to help you to learn how to use the compiler.
Open the project in ASPC IDE and compile it. Then open VB and make the DLL - Go to the File menu and select "Make WSHHello.DLL". Having the DLL ready you need just to go to the compiled directory and start the loader file - simple.vbs. The directory and the file are created after building the project. Take a look at the original file (from src directory) and this one. Of course this one line example makes the loader file bigger than the original one but you can see how the loader files work in this simple case - without any side effects.
Directory: asp\hello
This example contains 3 ASP pages with an include file (pages are some of the typical examples used to learn ASP). Original files are in the src directory and the include file is in a subdirectory src\includes.
Open and compile the project with ASPC IDE. Make the DLL using VB and view the same examples but now using the loader pages in the compiled directory. The sample is not something unusual as ASP code but during the build you will see some warnings of type:
In class X array (VarName) is declared public. Changing to Private, but this may cause your application to run incorrectly.
The purpose of the example is to take your attention over the problem. As you can see these warnings do not cause problems in its functionality. And you can ignore such warnings if the compiled ASP pages contain plain code and some Sub-s and Function-s but no VBScript classes. Automatic change of the access rights will not cause problems because these arrays are accessed only from within the page code and not from another VBScript classes (See also the chapters for the execution contexts in the ASPC documentation). If you want to correct the samples find those array declarations and declare these arrays with Private keyword instead of Dim.
Directory: asp\configurable
It is not a rare case - a set of ASP pages can be used again for another client or in another project by just changing a few initial values of some variables in them. When ASP pages are used they are often copied to a new location and edited to set these values for the case. Using ASPC you have two opinions - to compile all of them in different DLL-s or to make something more effective - to compile them once and set these valuse from outside - i.e. use properties of the classes ASPC created from your pages.
The sample uses a very simple MS Access DB and lists products of a company (Of course all the details are omitted). The DB contains data for two companies - ACME Company in DB table ACME, and Good Company in the DB table GOODCOMPANY. As you can see to use the same page for the different companies you just need to tell to the pages which table must be used and (as the example needs) tell what is the display name of the company.
Compile the project and build the DLL. Then if you start the loader file (products.asp) in the compiled directory you will get an SQL statment syntax error. It occurs because the original ASP file uses '#! Discard ASPC directive and statements intended to set the table name and company name are discarded by ASPC. This allows you to set these values from the outside. Do the following make a copy of the product.asp loader file in the compiled directory. Open one of the copies and see the comments generated by ASPC. It reminds you that Discard directive was used and thus the page needs some values to be set in order to work. In the comments are listed the discarded statements. Now replace the comments with this code for example:
proc.CompanyDisplayName = "ACME Inc."
proc.CompanyName = "ACME"
For ACME company or with
proc. CompanyDisplayName = "Good Company Ltd."
proc. CompanyName = "GOODCOMPANY"
for the Good Company products. Now the page will work ok and will list the products of the configured company. Now setting the first pair of the above values in the first file and the second pair in the second file (copied as mentioned above) you have two ASP loader files using the same component but configuring it to work with different settings.
This method can be used for many other purposes - the Discard directive allows you to leave some code to be written in the loader page instead of compiling it into the DLL. Planning carefully what to be included and what to be set from the outside the components generated can be made flexible and reusable.
Directory: asp\DynLinks
This sample uses VBScript class defined in the common include file - DynLinks.inc. The sample allows you to add links and save them to a file and then list them on a page (It can be used for a personal start page on your machine).
The VBScript class DynLink implements the most of the functionality of the example. The ASP pages which use it are quite simple and they are only using its methods. Thus these pages can be easily redesigned or using different files to store different categories of links pages may be enhanced to hold wide range of links user wants to see on his start page.
The sample illustrates a typical case in ASP programming - ASP files with include files and many language features used. As you can see the original files in the src directory work as well thus no specific techniques are required when VBScript classes are used. ASPC takes care to connect them to the VB class packing the resting part of the pages and if you look at the code in the generated project you will see that the class in the include file is converted to VB class too.
No directives are used in the sample - see the next one for an idea how far the crazy ideas may lead :).
Directory: components\component
This sample shows an idea how to do something much more reusable. There is an ASP page in the src directory, but it is not intended to be executed. It contains a set of routines planned to work together. Some of them are generating HTML code the other expect some data in the request and do something. In other words this page will become a component which will be used in another - not compiled ASP pages to do the most difficult part of the work and leave only the design tasks to be done in them. Of course these pages can be compiled too - but as you can see later - there is no general reason to do so.
You will find the pages using the component in the components\component\test subdirectory of the project folder. Start the listusers.asp - it provides links to the other pages.
Descriptions of the following examples contain only notes about their purpose (as examples). They are simple thus their actual work can be understood by looking at the code or just starting them.
Directory: asp\DbgTrace
This example is the Hello World example with one important addition - the newObjects.utilctls.TraceMsg component is used. This component is provided with ASP Compiler for developers' convenience. It implements a method which allows debug trace messages to be issued from the script or compiled code. It can be used as stand-alone component in any of your applications. ASP compiler provides the DbgTrace directive which enables/disables the corresponding statements. With this component this directive allows you to discard the debug statements from the compiled code when performing release build.
To use this component you will need additional tool - which shows the debug messages. ASPC does not provide such functionality because such tools exist as freeware on the Internet. Probably the best one is the DebugView of Sysinternals - which supports trapping of messages from another machines on the network and filtering.
What is the reason to use such feature? This component allows you to issue messages from any application - including application working on the WEB server. Sometimes logical mistakes are hard to find and some trace messages are exactly what the developer needs in order to find the problem. It is very hard to trace an ASP page or sometimes the problem occurs only in the productive environment. Thus using the TraceMsg object you can issue them from the ASP page (no matter if it compiled or not) while it works. The object is Free-Threaded thus you can place it in the Session variable and enable debugging for one session (yours). Yes it is possible to issue such messages directly in the output but adding them one by one brings the page layout which is hard to understand even for the developer. Thus trapping the messages with additional tool from outside leaves the page visual output intact.
Directory: components\Simplelib
This example illustrates a typical scenario - converting an ASP include file (s) to component. Assuming you have include file (s) with library routines and you want to pack them in a component and use it instead of including a large number of files in every page and use only few routines from them. In this case you need to create an empty ASP page which includes these files (no matter how - one of them may be responsible to include others for example) and use that page as input for the compiler. Also you will need to use the ClassName directive to specify the class name explicitly (Don't forget you are going to use in many pages - an automatically generated name will not make any sense).
After doing so you will are able to use the DLL where some routines are required by creating it as any other COM object and initialize it. E.g. you will need to pass a bit of environment information, call the ASPCExecuteClass to perform any global initialization corresponding to the initial script behavior and after this point you are free to call every member of the component - Members will correspond to the routines in the original ASP include file.
Src directory contains the dummy.asp file - used as input - it just includes the library (which is in the includes directory). Normal.asp file is a sample which uses the include file as usual for every ASP page. After building the DLL look in the test folder and use the test1.asp file which uses the compiled component. Of course there are differences between initial usage and usage of the compiled version of the library. Thus this technique is applicable if you want to maintain your library in compiled form - porting the existing pages may need some manual work and will be easier to just compile them all for example.
It is interesting for us if such kind of usage is important for you. We can add an option in the next versions which allows a page to be adopted to a compiled version of some include file (s).
Directory: components\plain1
This sample is similar to the sample 5 but it is more simple and does not use any specific host features. It is intended to work as usual component. Thus it has no namespaces configured and does not need initialization to be performed before its usage. Think for it mostly as for an alternative way to build an ActiveX using script. In fact this can be done using just VB but for the script programmers it will be easier to think for their component as for a script file and using the ASPC convert it to a COM component.
Look in the test directory for an WSH script and DHTML page using the compiled component.
This sample does not include important global code, but if you want to do something in the global part see the next example.
Directory: components\plain2
This example is a bit more complex than the previous. In fact it contains two classes - one will be created from the code in the global part and the other will correspond to the Generator class - defined as VBScript class. to use the component you will need to create the Creator class (see the ClassName directive in the beginning of the file which specifies what class name will be used for the class created from the global code). You will need to initialize it and use its member to create Generator objects which will be used later.
See in the test directory for an WSH script which uses the compiled component.
When using such a technique you may think for the COM class corresponding to the plain part of the script as for a Root class which is responsible to create objects of the other class in the source file. ASP Compiler preserves the connection between them thus it is possible to use global variables from within the members of these classes. Thus you need not just to create the object of this Root class but also call its ASPCExecuteClass member before using its members This will guarantee the class is properly initialized.
Directory: vb\component
This example is intended for VB programmers. They are able to use ASP pages as source for creation of component which can be used to fill hosted WEB browsers with HTML content without need of WEB server or even an ASP engine like ALP. There are many limitations of this techniques but it can be useful quite often.
The sample contains a VB project named iehost. It implements a simple EXE which hosts the WEB browser control. Instead of directing it to an URL the sample loads the compiled component, sets some of its properties and invokes it to generate the content for the hosted control. This makes the exe self responsible for the content generation in the WEB browser hosted in it.
Such kind of projects need a specific setting - you need not to use Response.Write in your page and you need to configure the project to generate Something else instead of Response.Write when parsing the <% %> and <%= %> tags. Write is a reserved word in VB thus youwill need to choose another name for this method - for example Response.PutString. Use the project settings to set up it. Then you will need to provide such a method in your form and pass the form instead of Response object to the component. Thus the component will "think" it runs in ASP environment, but as you can see there are limitations caused by the absence of the other ASP objects - you will need to remove them from the project and make sure your page does not use them. It is obvious you are able to avoid usage of the Request object - global variables in your ASP page are accessible as properties thus you are able to fill data in them and modify the page to not use the Request object. From this point further simulation of another ASP objects is possible too but is it worth to do so? They are related to certain WEB functionality thus when using this technique evaluate if it will be enough good for the case and will not require too much additional code. Furthermore note that you cannot use images in the generated content without depending on some protocol such as http, file and so on. It is possible to generate such URLs but this may become quite difficult task, thus form some point of complexity it will be better to install ASP processor (such as ALP on the machine) or use WEB server and work with the hosted browser in a typical manner - passing URL to it.
As a conclusion: If you need a content for a hosted browser in a desktop application and you need to use it mostly as more universal visual control - able to show tables, formatted text, integrate some internal scripts and you do not need images in it you can see if the ASPC is able to help you to do this without need of additional software. But if the work with this control goes to become more complex it is better to find a product which will act as typical WEB server.